Skip to main content

Audience API

Overview​

The Audience API allows you to create different types of Audiences for Healthcare Campaigns. The following table describes some of the Audience types:

TypeDescription
Matched AudienceUpload a CSV or XLSX file with Audience details which is then matched with IQM's user database to create a custom Audience segment.
ABM AudienceAccount-Based Marketing for healthcare Campaigns.

More resources:

Authentication​

Use the following header parameters for all requests:

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Worskpace ID Header

Matched Audience​

Matched Audience Details​

GET /api/v2/audience/matched/{id}

Get Matched Audience details by ID.

Path Parameter
id
string		Matched Audience ID
Response Properties
id
integer		Audience ID
audienceName
string		Audience name
existingColumnMatching
string		Matched Audience file columns mapped with system fields in JSON serialized string format
columnSettings
string		Matched Audience columns settings as per the selected columns for matching in JSON serialized string format
metadata
string		Matched Audience sample data with system fields in JSON serialized string format
status
string		Audience status
matchRate
integer		The percentage of matched records compared to a reference set
minEcpm
integer		Minimum effective cost per mille
maxEcpm
integer		Maximum effective cost per mille
s3FileName
string		Audience file name
included
integer		Count of Campaigns including this Audience
excluded
integer		Count of Campaigns excluding this Audience
createdDate
integer		Unix epoch creation date, in milliseconds
modifiedDate
integer		Modified date
organizationName
string		Organization name
userEmail
string		User email
userName
string		User name
expectedSpent7
integer
expectedSpent30
integer
expectedSpent60
integer
dataCost
integer		Fees charged by the platform if the Audience is used in any Campaign
fileTotalCount
integer		Number of records updated in a Matched Audience file
owId
integer		Organization Workspace ID
uowId
integer		User Organization Workspace ID
uniques
integer		Count of unique Audiences reached
verticalId
integer		Vertical ID
isApprovalAcces
boolean		Indicates if user has access to approve
isEditAccess
boolean		Indicates if user has edit access for the requested resource
isSingleColumnEnabled
boolean		Flag to indicate if the mapping is single column enabled, if the voterId/phone/email/full-address is the primary column mapping then this should be true, and false otherwise. Default value: false
Response 200
{
  "statusCode": 200,
  "responseObject": {
    "id": 12345,
    "audienceName": "Sample audience",
    "existingColumnMatching": "{\"LALVOTERID\":\"Voters_ID\"}",
    "columnSettings": "{\"Voters_ID\":\"LalVoterID\"}",
    "metadata": "{\"voterIDColumn\":[\"LALVOTERID\"],\"columns\":[\"LALVOTERID\",\"Residence_Addresses_Zip\",\"Residence_Addresses_State\",\"Voters_FirstName\",\"Voters_LastName\"],\"fileName\":\"matched_audience fn-ln-st-zp.csv\",\"fileSize\":17915,\"rows\":0,\"columnValues\":{\"LALVOTERID\":[\"LALNY106413966\",\"LALNY111849285\",\"LALNY110212948\"],\"Residence_Addresses_Zip\":[\"11021\",\"11050\",\"11050\"],\"Residence_Addresses_State\":[\"NY\",\"NY\",\"NY\"],\"Voters_FirstName\":[\"Mei\",\"Carole\",\"Erin\"],\"Voters_LastName\":[\"Liu\",\"Visconti\",\"Orr\"]}}",
    "status": "Processing",
    "matchRate": 0,
    "minEcpm": 0,
    "maxEcpm": 0,
    "s3FileName": "Test audience voter id",
    "included": 0,
    "excluded": 0,
    "createdDate": 1683200348,
    "modifiedDate": 1683200348,
    "organizationName": "Sample orgranization name",
    "userEmail": "sample@example.com",
    "userName": "Dummy User",
    "expectedSpent7": 0,
    "expectedSpent30": 0,
    "expectedSpent60": 0,
    "dataCost": 0,
    "fileTotalCount": 502,
    "owId": 1000001,
    "uowId": 10001,
    "uniques": 0,
    "verticalId": 8,
    "isApprovalAccess": false,
    "isEditAccess": true,
    "isSingleColumnEnabled": true
  }
}

Create Matched Audience​

POST /api/v2/audience/matched/add

Create a Matched Audience.

Payload (Form Data)

columns *
string (FormData)

Matched Audience file columns mapped with system fields. This supports a few columns mapping as follows:
  • NPI_ID
    • Sample value: { "NPI_ID_VALUE": "NPI_ID" }

columnSettings
string (FormData)

Matched Audience columns setting as per the selected columns for matching. Column setting should be as per the selected column as follows:

  • NPI_Id
    • Value must be a supported healthcare Data Partners ID
    • Sample value: { "NPI_ID": "healthcare_id" }

audienceName
string (FormData) required		Name of matched audience
metadata
string (FormData) required		Matched Audience sample data with system fields
fileTotalCount
integer (FormData) required		Total number of records in the uploaded Audience file
isSingleColumnEnabled
boolean (FormData) required		Flag to indicate if the mapping is single column enabled, if the voterId/phone/email/full-address is the primary column mapping then this should be true, and false otherwise. Default value: false
Response Properties
id
integer		Audience ID
message
string		Success message
Request Sample (FormData)
------WebKitFormBoundary2LAoPYE0pJvRQ6mQ
Content-Disposition: form-data; name="file"; filename="matched-audience-example.csv"
Content-Type: text/csv

------WebKitFormBoundary2LAoPYE0pJvRQ6mQ
Content-Disposition: form-data; name="columns"

{"first-name":"Voters_FirstName","last-name":"Voters_LastName","zip":"Residence_Addresses_Zip","state":"Residence_Addresses_State","street-address":"Residence_Addresses_AddressLine"}
------WebKitFormBoundary2LAoPYE0pJvRQ6mQ
Content-Disposition: form-data; name="metadata"

{"columns":["registered-voter-id","l2-voter-id","targetsmart-voter-id","first-name","last-name","street-address","city","zip","zipplus4","state","full-address","phone","email","phone-sha256","email-sha256","npi-id"],"fileName":"matched-audience-example.csv","fileSize":1777,"columnValues":{"registered-voter-id":["23457","456789","34567"],"l2-voter-id":["LALNY987654","LALNY76543","LALNY54321"],"targetsmart-voter-id":["NY-000020745","NY-000032452","NY-000069778"],"first-name":["Bilbo","Frodo","Samwise"],"last-name":["Baggins","Baggins","Gamgee"],"street-address":["11 The Shire Middle Earth","22 The Shire Middle Earth","33 The Shire Middle Earth"],"city":["New York","New York","New York"],"zip":["10001","10010","10011"],"zipplus4":["1122","2233","3344"],"state":["NY","New York","NY"],"full-address":["11 The Shire Middle Earth, New York, 10001, NY","22 The Shire Middle Earth, New York, 10010, NY","33 The Shire Middle Earth, New York, 10011, NY"],"phone":["3456789012","5678901234","7890123456"],"email":["Bilbo.Baggins@lotr.com","Frodo.Baggins@lotr.com","Samwise.Gamgee@lotr.com"],"phone-sha256":["26cc49f1a2133f3784b937017f9cc86e05b5413c7f91b0b6bd6375631b68371e","2f510ce904687db4b2706fdaf33f1d0e678be13cc5fe300cf695a546befa5fc8","453fc17260d034186d92d1e58cc557fea9cafc1bf886154b472057feed950605"],"email-sha256":["43f5f8fabe82fc8dce2452267f5550bb036d0ddf33368682a9cd5da8286d63a0","ceb005d969f16f9a6a487849d27bf854fac1f0733aa61995bcbb5cb928dfc410","986c1ae0d3cef60591d3b29aa54afb5d9654406d7cfa4fcbb65c3ad45ad1ce5c"],"npi-id":["1144317652","1467478172","1275506503"]},"rows":5}
------WebKitFormBoundary2LAoPYE0pJvRQ6mQ
Content-Disposition: form-data; name="audienceName"

Matched Audience Sample
------WebKitFormBoundary2LAoPYE0pJvRQ6mQ
Content-Disposition: form-data; name="isSingleColumnEnabled"

false
------WebKitFormBoundary2LAoPYE0pJvRQ6mQ
Content-Disposition: form-data; name="fileTotalCount"

5
------WebKitFormBoundary2LAoPYE0pJvRQ6mQ--
Response 200
{
   "statusCode": 200,
   "responseObject": {
       "id": 15332,
       "message": "Audience created successfully"
   }
}

Update Matched Audience​

PATCH /api/v2/audience/matched/update/{matched_audience_id}

Update a Matched Audience.

Path Parameter
matched_audience_id
integer		Matched Audience ID
Request Schema
audienceName
string		Audience Name
rawS3URL
string		Raw S3 URL
Response Properties
id
integer		Audience ID
message
string		Success message
Request Sample
{
  "audienceName": "Sample audience name",
  "rawS3URL": "s3://sample.url.come"
}
Response 200
{
  "statusCode": 200,
  "responseObject": {
    "id": 1,
    "message": "Your changes have been saved successfully"
  }
}

Healthcare Data Details​

ABM Audience Details​

GET /api/v3/audience/abm/{audienceId}

Get ABM Audience details by ID.

Path Parameter
audienceId
integer		ABM Audience ID
Response Properties
id
integer		Audience ID
name
string		Audience name
status
string		Audience status
audienceTypeId
integer		Audience Type ID
createdAt
integer		Unix epoch timestamp of Audience creation
partnerName
string		Partner name
partnerLogoUrl
string		Partner logo URL
uniques
integer		Count of unique Audiences reached
dataCost
integer		Fees charged by the platform if the Audience is used in any Campaign
filters
object		Frequency type
filter object properties
dataProviderIds
array of integers		Data Provider IDs
accountIds
array of integers		Account IDs
accountTypeIds
array of integers		Account type IDs
accountSubTypeIds
array of integers		Account Subtype IDs
countryIds
array of integers		Country IDs
stateIds
array of integers		State IDs
cityIds
array of integers		City IDs
titleIds
array of integers		Title IDs
specialityIds
array of integers		Speciality IDs
ids
array of integers		IDs
pageNo
array of integers		Page number of retrieved data
noOfEntries
array of integers		Number of entries returned
Response 200
{
  "success": true,
  "data": {
    "id": 1124243,
    "name": "Test ABM audience",
    "status": "Processing",
    "audienceTypeId": 9,
    "createdAt": 1739261114,
    "partnerName": "Healthlink",
    "partnerLogoUrl": "www.sample.com",
    "uniques": 1000,
    "dataCost": 10,
    "healthCareDataMappingIds": [
      13572,
      13575,
      32777
    ],
    "filters": {
      "ids": [
        13572,
        13575,
        32777
      ],
      "dataProviderIds": [
        1
      ],
      "healthCareSystemIds": [
        1,
        2,
        3
      ],
      "accountIds": [
        1,
        2,
        3
      ],
      "accountTypeIds": [
        1,
        2,
        3
      ],
      "accountSubTypeIds": [
        1,
        2,
        3
      ],
      "titleIds": [
        1,
        2,
        3
      ],
      "specialityIds": [
        1,
        2,
        3
      ],
      "countryIds": [
        30100001
      ],
      "stateIds": [
        1,
        2,
        3
      ],
      "cityIds": [
        1,
        2,
        3
      ],
      "pageNo": 1,
      "noOfEntries": 10000
    }
  }
}

ABM Audience statistics​

GET /api/v3/audience/abm/{audienceId}/healthcare-data-statistics

Get ABM Audience statistics by ID.

Path Parameter
audienceId
integer		ABM Audience ID
Response Properties
healthSystem
integer		Healthcare System ID
account
integer		Healthcare Account ID
accountType
integer		Healthcare Account Type ID
npiReach
integer		NPI reach
speciality
integer		Healthcare Specialty ID
Response 200
{
  "success": true,
  "data": {
    "healthSystem": 2,
    "account": 4,
    "accountType": 8,
    "npiReach": 25513,
    "speciality": 3
  }
}

Healthcare Titles List​

GET /api/v3/audience/abm/healthcare-data/title

Get a list of healthcare titles.

Query Parameters
dataProviderIds
array of integers		Data Provider IDs
pageNo
integer		Page number for the data, default: 0
noOfEntries
integer		Maximum number of entries returned, default: 50
searchField
string		Search results by keyword
Response Properties
id
integer		Title ID
displayName
string		Title name
displayOrder
integer		Display order
Response 200
{
  "success": true,
  "data": {
    "titleList": [
      {
        "id": 1,
        "displayName": "Healthcare Title 1",
        "displayOrder": 1
      },
      {
        "id": 2,
        "displayName": "Healthcare Title 2",
        "displayOrder": 20
      }
    ],
    "filteredRecords": 5,
    "totalRecords": 3294
  }
}

Healthcare Specialties List​

GET /api/v3/audience/abm/healthcare-data/speciality

Get a list of healthcare specialties.

Query Parameters
dataProviderIds
array of integers		Data Provider IDs
pageNo
integer		Page number for the data, default: 0
noOfEntries
integer		Maximum number of entries returned, default: 50
searchField
string		Search results by keyword
Response Properties
id
integer		Specialty ID
displayName
string		Specialty name
displayOrder
integer		Display order
Response 200
{
  "success": true,
  "data": {
    "specialityList": [
      {
        "id": 1,
        "displayName": "Healthcare Speciality 1",
        "displayOrder": 1
      },
      {
        "id": 2,
        "displayName": "Healthcare Speciality 2",
        "displayOrder": 20
      }
    ],
    "filteredRecords": 5,
    "totalRecords": 3294
  }
}

Healthcare Systems List​

GET /api/v3/audience/abm/healthcare-data/healthcare-system

Get a list of healthcare systems.

Query Parameters
dataProviderIds
array of integers		Data Provider IDs
pageNo
integer		Page number for the data, default: 0
noOfEntries
integer		Maximum number of entries returned, default: 50
searchField
string		Search results by keyword
Response Properties
id
integer		System ID
displayName
string		System name
displayOrder
integer		Display order
Response 200
{
  "success": true,
  "data": {
    "healthcareSystemList": [
      {
        "id": 1,
        "displayName": "Healthcare System 1",
        "displayOrder": 1
      },
      {
        "id": 2,
        "displayName": "Healthcare System 2",
        "displayOrder": 20
      }
    ],
    "filteredRecords": 5,
    "totalRecords": 3294
  }
}

Healthcare Data​

POST /api/v3/audience/abm/healthcare-data

Get a healthcare data list by specified filters.

Query Parameters
dataProviderIds
array of integers		Data Provider IDs
pageNo
integer		Page number for the data, default: 0
noOfEntries
integer		Maximum number of entries returned, default: 50
healthCareSystemIds
array of integers 		Healthcare system IDs
accountNameIds
array of integers 		Account name IDs
accountTypeIds
array of integers 		Account type IDs
accountSubTypeIds
array of integers 		Account subtype IDs
countryIds
array of integers 		Country IDs
stateIds
array of integers 		State IDs
cityIds
array of integers 		City IDs
titleIds
array of integers 		Title IDs
specialityIds
array of integers 		Specialty IDs
ids
array of integers 		IDs
Response Properties
id
integer		Audience ID
cost
integer		Charges for a specific segment
reach
integer		Unique reach of segments (i.e. Audience reach)
healthCareSystemId
integer		Healthcare System ID
healthCareSystemName
string		Healthcare System name
accountId
integer		Healthcare Account ID
accountName
string		Healthcare account name
accountTypeId
integer		Healthcare Account Type ID
accountTypeName
string		Healthcare Account type name
accountSubTypeId
integer		Healthcare Account Subtype ID
accountSubTypeName
string		Healthcare Account subtype name
titleId
integer		Healthcare Title ID
titleName
string		Healthcare title name
specialityId
integer		Healthcare Specialty ID
specialityName
string		Healthcare specialty name
countryId
integer		Country ID
countryName
string		Country name
stateId
integer		State ID
stateName
string		State name
cityId
integer		City ID
cityName
string		City name
dataProviderId
integer		Data Provider ID
dataProviderName
string		Data provider name
Request Sample
{
  "dataProviderIds": [
    1
  ],
  "healthCareSystemIds": [
    40100004,
    40100007
  ],
  "accountIds": [
    40208104,
    40628423
  ],
  "accountTypeIds": [
    40300003
  ],
  "accountSubTypeIds": [
    40400001,
    40400010
  ],
  "countryIds": [
    30100001
  ],
  "stateIds": [
    30200028,
    30200043
  ],
  "cityIds": [
    30430356,
    30447825,
    30447952,
    30448122
  ],
  "titleIds": [
    40500099
  ],
  "specialityIds": [
    40500014,
    40500086
  ],
  "ids": [
    1,
    2,
    3
  ],
  "pageNo": 1,
  "noOfEntries": 2
}
Response 200
{
  "success": true,
  "data": {
    "totalRecords": 52265,
    "filteredRecords": 5,
    "healthCareData": [
      {
        "id": 1,
        "cost": 10,
        "reach": 1,
        "healthCareSystemId": 40100004,
        "healthCareSystemName": "ABCD PEDIATRICS",
        "accountId": 40628423,
        "accountName": "Stepping Stone Pediatrics PA",
        "accountTypeId": 40300003,
        "accountTypeName": "Group Practice",
        "accountSubTypeId": 40400010,
        "accountSubTypeName": "Telephone/E-Mail Order Pharmacy",
        "titleId": 40500099,
        "titleName": "MD",
        "specialityId": 40500086,
        "specialityName": "Gastroenterology",
        "countryId": 30100001,
        "countryName": "United States",
        "stateId": 30200043,
        "stateName": "Tennessee",
        "cityId": 30447952,
        "cityName": "Franklin, TN",
        "dataProviderId": 1,
        "dataProviderName": "HealthCarelink"
      },
      {
        "id": 2,
        "cost": 10,
        "reach": 1,
        "healthCareSystemId": 40100004,
        "healthCareSystemName": "ABCD PEDIATRICS",
        "accountId": 40628423,
        "accountName": "Stepping Stone Pediatrics PA",
        "accountTypeId": 40300003,
        "accountTypeName": "Group Practice",
        "accountSubTypeId": 40400010,
        "accountSubTypeName": "Telephone/E-Mail Order Pharmacy",
        "titleId": 40500099,
        "titleName": "MD",
        "specialityId": 40500086,
        "specialityName": "Gastroenterology",
        "countryId": 30100001,
        "countryName": "United States",
        "stateId": 30200043,
        "stateName": "Tennessee",
        "cityId": 30447825,
        "cityName": "Brentwood, TN",
        "dataProviderId": 1,
        "dataProviderName": "HealthCarelink"
      }
    ]
  }
}

Healthcare Statistics​

POST /api/v3/audience/abm/healthcare-data/statistics

Get healthcare statistics details.

Query Parameters
dataProviderIds
array of integers		Data Provider IDs
pageNo
integer		Page number for the data, default: 0
noOfEntries
integer		Maximum number of entries returned, default: 50
healthCareSystemIds
array of integers 		Healthcare system IDs
accountNameIds
array of integers 		Account name IDs
accountTypeIds
array of integers 		Account type IDs
accountSubTypeIds
array of integers 		Account subtype IDs
countryIds
array of integers 		Country IDs
stateIds
array of integers 		State IDs
cityIds
array of integers 		City IDs
titleIds
array of integers 		Title IDs
specialityIds
array of integers 		Specialty IDs
ids
array of integers 		IDs
Response Properties
healthSystem
integer		Healthcare System ID
account
integer		Healthcare Account ID
accountType
integer		Healthcare Account Type ID
npiReach
integer		NPI reach
speciality
integer		Healthcare Specialty ID
Request Sample
{
  "dataProviderIds": [
    1
  ],
  "healthCareSystemIds": [
    40100004,
    40100007
  ],
  "accountIds": [
    40208104,
    40628423
  ],
  "accountTypeIds": [
    40300003
  ],
  "accountSubTypeIds": [
    40400001,
    40400010
  ],
  "countryIds": [
    30100001
  ],
  "stateIds": [
    30200028,
    30200043
  ],
  "cityIds": [
    30430356,
    30447825,
    30447952,
    30448122
  ],
  "titleIds": [
    40500099
  ],
  "specialityIds": [
    40500014,
    40500086
  ],
  "ids": [
    1,
    2,
    3
  ],
  "pageNo": 1,
  "noOfEntries": 2
}
Response 200
{
  "success": true,
  "data": {
    "healthSystem": 2,
    "account": 4,
    "accountType": 8,
    "npiReach": 25513,
    "speciality": 3
  }
}

Healthcare Account Types​

POST /api/v3/audience/abm/healthcare-data/account-type

Get a list of healthcare account types.

Query Parameters
dataProviderIds
array of integers		Data Provider IDs
pageNo
integer		Page number for the data, default: 0
noOfEntries
integer		Maximum number of entries returned, default: 50
healthCareSystemIds
array of integers 		Healthcare system IDs
accountNameIds
array of integers 		Account name IDs
searchField
string		Search results by keyword
Response Properties
id
integer		Account ID
displayName
string		Account name
displayOrder
integer		Display order
Request Sample
{
  "pageNo": 1,
  "noOfEntries": 20,
  "searchField": "Sample Text",
  "dataProviderIds": [
    1
  ],
  "healthcareSystemIds": [
    1,
    2,
    3
  ],
  "accountNameIds": [
    4,
    5,
    6
  ]
}
Response 200
{
  "success": true,
  "data": {
    "accountTypeList": [
      {
        "id": 1,
        "displayName": "Account Type 1",
        "displayOrder": 1
      },
      {
        "id": 2,
        "displayName": "Account Type 2",
        "displayOrder": 2
      }
    ],
    "filteredRecords": 5,
    "totalRecords": 3294
  }
}

Healthcare Account Subtypes​

POST /api/v3/audience/abm/healthcare-data/account-subtype

Get a list of healthcare account subtypes.

Query Parameters
dataProviderIds
array of integers		Data Provider IDs
pageNo
integer		Page number for the data, default: 0
noOfEntries
integer		Maximum number of entries returned, default: 50
healthCareSystemIds
array of integers 		Healthcare system IDs
accountNameIds
array of integers 		Account name IDs
searchField
string		Search results by keyword
accountTypeIds
array of integers 		Account type IDs
Response Properties
id
integer		Account subtype ID
displayName
string		Account sub name
displayOrder
integer		Display order
Request Sample
{
  "pageNo": 1,
  "noOfEntries": 20,
  "searchField": "Sample Text",
  "dataProviderIds": [
    1
  ],
  "healthcareSystemIds": [
    1,
    2,
    3
  ],
  "accountNameIds": [
    4,
    5,
    6
  ],
  "accountTypeIds": [
    7,
    8,
    9
  ]
}
Response 200
{
  "success": true,
  "data": {
    "accountSubTypeList": [
      {
        "id": 1,
        "displayName": "Account Subtype 1",
        "displayOrder": 1
      },
      {
        "id": 2,
        "displayName": "Account Subtype 2",
        "displayOrder": 2
      }
    ],
    "filteredRecords": 5,
    "totalRecords": 3294
  }
}

Healthcare Account Names​

POST /api/v3/audience/abm/healthcare-data/account-name

Get a list of healthcare account names.

Query Parameters
dataProviderIds
array of integers		Data Provider IDs
pageNo
integer		Page number for the data, default: 0
noOfEntries
integer		Maximum number of entries returned, default: 50
healthCareSystemIds
array of integers 		Healthcare system IDs
searchField
string		Search results by keyword
Response Properties
id
integer		Account name ID
displayName
string		Account name
displayOrder
integer		Display order
Request Sample
{
  "pageNo": 1,
  "noOfEntries": 20,
  "searchField": "Sample text",
  "dataProviderIds": [
    1
  ],
  "healthcareSystemIds": [
    1,
    2,
    3
  ]
}
Response 200
{
  "success": true,
  "data": {
    "accountNameList": [
      {
        "id": 1,
        "displayName": "Account Name 1",
        "displayOrder": 1
      },
      {
        "id": 2,
        "displayName": "Account Name 2",
        "displayOrder": 20
      }
    ],
    "filteredRecords": 5,
    "totalRecords": 3294
  }
}